home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / utilities / monitor / serlog12.lha / serlog / Readme
Encoding:
Text File  |  1994-09-03  |  6.0 KB  |  165 lines
  1.  
  2.  
  3.  
  4.                               SERLOG.DEVICE
  5.  
  6.  
  7. Preface
  8. ~~~~~~~
  9.   Space - the final frontier! These are the vo... oh, sorry :-)
  10.   "serlog.device" is a special purpose debugging tool which allows you to
  11.   monitor serial-IO.
  12.   I wrote this when trying to track down some problems with my FAX-Software
  13.   and was ask to make it available to other people.
  14.  
  15.  
  16. Legal stuff
  17. ~~~~~~~~~~~
  18.   serlog.device is Copyright (c) by the author Stefan Pröls.
  19.   It is released as FREEWARE meaning that you may distribute and use it in
  20.   any form without limitations.
  21.   There is absolutely no warranty on any part of this package.
  22.   Use it on your own risk.
  23.  
  24.  
  25. Technical Overview
  26. ~~~~~~~~~~~~~~~~~~
  27.   serlog.device passes all IOExtSer requests to a "real" serial.device
  28.   and writes the results to a file.
  29.   You may configure the amount of information to be stored in the log.
  30.   The log-file created by serlog.device contains a binary dump which can
  31.   be formatted (i.e. transferred into a readable version) using the supplied
  32.   formatter.
  33.  
  34.   Note that serlog.device uses *significant* overhead over the underlying
  35.   serial.device, resulting in very low baud-rates.
  36.  
  37.   OS 2.0 or greater is required.
  38.  
  39.  
  40. Installation
  41. ~~~~~~~~~~~~
  42.   Just copy "serlog.device" to "DEVS:" and the supplied programs "slprefs"
  43.   and "fmtlog" to any place you want.
  44.   If you have a CPU >= 68020 use the binaries from the bin020 directory,
  45.   otherwise use the ones from bin000.
  46.  
  47.   If you have problems with the speed try to reduce mulitasking while
  48.   serial.device is in use and try to hold most things in 32 Bit FAST
  49.   memory. E.g. "CPU FASTROM" will result in a significant speed-up on
  50.   68030 CPUs using 16-Bit ROMS (e.g. A2k-30).
  51.  
  52.   Using high-speed connections hardware-overflow errors may occure.
  53.   However, sensible protocols should handle them.
  54.  
  55.  
  56. Usage
  57. ~~~~~
  58.   Tell the software you want to debug to use "serlog.device" unit 0 instead
  59.   of "serial.device".
  60.  
  61.   Before you start the program you should tell the device what to monitor.
  62.   "slprefs" is used for that.
  63.  
  64.   "slprefs" is a shell-driven -- sorry ;-) -- preferences utility for the
  65.   serlog.device. Basically it allows you to turn on and off monitoring of
  66.   certain commands like "CMD_READ". To do so specify the appropirate commands
  67.   and append "ADD" or "SUB" to the command line. You may get a list of possible
  68.   commands by the includes or by typing "slprefs ?".
  69.   There are some more options:
  70.  
  71.     DEVICE      -- The underlying device used to execute commands.
  72.                    E.g. "serial.device".
  73.  
  74.     UNIT        -- The unit of the underlying device.
  75.                    DO NOT MIX THIS UP with the unit of "serlog.device"!
  76.                    serlog.device supports *ONLY* unit *0*.
  77.                    If you have some kind of multi-IO board you may for example
  78.                    specify "DEVICE=multiio.device UNIT=2" which means that
  79.                    "serlog.device" when opened for unit *0* will use unit 2
  80.                    of "multiio.device".
  81.  
  82.     FILENAME    -- Captains log. This is the name of the file the protocol
  83.                    will be written to.
  84.  
  85.     SHOW        -- Shows the current settings. They are always shown but when
  86.                    this option is specified they will *only* be shown, i.e.
  87.                    changes will have no effect.
  88.  
  89.     CMD_*,
  90.     SDCMD_*     -- Commands to (or not to) monitor.
  91.  
  92.     ALL         -- Same as all (SD)CMD_*s.
  93.  
  94.     ADD         -- Turn on monitoring (SD)CMD_*s
  95.  
  96.     SUB         -- Turn off monitoring (SD)CMD_*s
  97.  
  98.     DEFAULTS    -- Reset all preferences to their default values.
  99.  
  100.     (NO)APPEND  -- When APPEND is on the log-file will not be deleted when
  101.                    OpenDevice() is called but all new data will be appended.
  102.                    Useful in case you're using "OwnDevUnit.library", for example.
  103.  
  104.   Note that any changes to the preferences will not have effect until the
  105.   device is restarted, i.e. when OpenDevice() (with exclusive access) is
  106.   called the next time.
  107.  
  108.  
  109.   The log-file created contains a binary dump of information about processed
  110.   IOExtSer requests. To create a readable output you use the "fmtlog" utility.
  111.  
  112.   If you do not specify a name for the log-file "fmtlog" will use the one set
  113.   with slprefs. "fmtlog" knows a few more or less useful options:
  114.  
  115.     GURULAYOUT  -- Do not create "nice" output but a very compact one.
  116.                    Normal human beings are likely to get completely mad
  117.                    when reading that. However, if you're a guru and you
  118.                    want to format a very large file which would produce
  119.                    an even larger output you may try this.
  120.  
  121.     BRIEF       -- Do not extract all available information but only a
  122.                    brief overview on what happened. Basically there will
  123.                    be no data for CMD_READ and CMD_WRITE.
  124.  
  125.     CDUMP       -- When dumping binary data use "\x??" notation for writing
  126.                    non-ASCII characters. Otherwise all non-printable
  127.                    characters will shown by ".".
  128.                    When CDUMP is specified some further 'C' like notations
  129.                    will be used, e.g. '\n' for NL or '\\' for "\". Quotes
  130.                    however will not be affected.
  131.                    This option has no effect when BRIEF is on.
  132.  
  133.  
  134. History
  135. ~~~~~~~
  136.   1.0   - works for me and only for me...
  137.   1.1   - temporary version
  138.   1.2   - complete rework, first public release
  139.           This is a major update - but as this isn't a SASG product this
  140.           doesn't matter.
  141.  
  142.  
  143. Target for flames
  144. ~~~~~~~~~~~~~~~~~
  145.   Ahm, flames? Hey, read the legal stuff above ;-) However, comments are
  146.   welcome. If you have any suggestions or if you think serlog.device is
  147.   THE tool you've been searching for for years any want to send me some
  148.   new Amigas or SUNs, feel free to contact me:
  149.  
  150.       Internet: proels@fmi.uni-passau.de
  151.       Fidonet:  Stefan Proels,2:2494/22.13
  152.  
  153.       Snailmail (ever heard about that?):
  154.  
  155.           Stefan Pröls
  156.           Rudolf-Guby-Str. 1
  157.           94032 Passau
  158.           Germany
  159.  
  160.           Earth
  161.  
  162.  
  163.       email is preferred.
  164.  
  165.